Skip to content

Feature Add positions DTOs and enhance invoicing #32

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Feature Add positions DTOs and enhance invoicing #32

wants to merge 2 commits into from

Conversation

kaspernowak
Copy link
Contributor

@kaspernowak kaspernowak commented Jun 15, 2025 •
edited
Loading

This PR introduces complete support for creating and sending invoices using structured DTOs, including all supported Bexio position types.

✅ What’s Included

  • New DTOs for all invoice position types:
    • AddDefaultPositionDTO
    • AddTextPositionDTO
    • ...and others under src/Dto/*
  • New request classes:
    • CreateAnInvoiceRequestNew
    • EditAnInvoiceRequestNew
    • SendAnInvoiceRequest
    • MarkAnInvoiceAsSentRequest
    • ...and Create, Edit, Delete, Fetch, and FetchList requests for all position types
  • New test coverage for the above requests and DTOs
  • Support for sending and marking invoices as sent via SendInvoiceDTO

💡 Usage Example

$invoiceDto = new CreateInvoiceDTO(
    title: 'Test',
    contact_id: $contacts->first()->id,
    // ...
    positions: [
        new AddTextPositionDTO(
            type: 'KbPositionText',
            text: (string) Str::uuid(),
            show_pos_nr: true
        ),
        new AddDefaultPositionDTO(
            type: 'KbPositionCustom',
            amount: 1,
            unit_id: $units->first()->id,
            account_id: 145,
            tax_id: $taxes->first()->id,
            text: Str::uuid(),
            unit_price: 100,
        ),
    ],
);

$invoice = $connector->send(new CreateAnInvoiceRequestNew(invoice: $invoiceDto))->dto();

$send = $connector->send(new SendAnInvoiceRequest(...));
$markAsSent = $connector->send(new MarkAnInvoiceAsSentRequest(...));

⚠️ Compatibility Note

The existing CreateAnInvoiceRequest class appears to be incompatible with the documented example due to a type mismatch in the filterPositions() method:

Argument #1 ($positions) must be of type Collection, array given

To avoid breaking changes, I've added new request classes (CreateAnInvoiceRequestNew, etc.) that work with the new DTO structure.
We may want to decide whether to:

  • Fix and maintain the old request for compatibility
  • Or deprecate it and focus solely on the updated approach

closes #7

@StanBarrows StanBarrows self-assigned this Jun 15, 2025
@StanBarrows StanBarrows marked this pull request as draft June 15, 2025 17:11
@kaspernowak kaspernowak marked this pull request as ready for review June 17, 2025 12:46
@kaspernowak kaspernowak force-pushed the feature/add-dtos-for-positions-and-enhance-invoicing branch from 20011fd to 14fefa3 Compare June 20, 2025 12:37
@StanBarrows StanBarrows requested a review from RhysLees June 30, 2025 22:46
@StanBarrows StanBarrows assigned RhysLees and unassigned StanBarrows Jun 30, 2025
@StanBarrows
Copy link
Contributor

@kaspernowak
We’ve just completed the OAuth PR and will take a closer look at this in the coming weeks.

@kaspernowak
Copy link
Contributor Author

kaspernowak commented Jul 2, 2025 •
edited
Loading

@StanBarrows Thank you! Looking forward to it. I think this would have higher prio than #34, as the structured addresses won't really be required before December.

@kaspernowak kaspernowak mentioned this pull request Jul 2, 2025
Open
@StanBarrows StanBarrows mentioned this pull request Jul 7, 2025
Open
6 tasks
@kaspernowak
Copy link
Contributor Author

@StanBarrows @RhysLees do you have an estimate of when you would have time to take a closer look at this?

@StanBarrows
Copy link
Contributor

@kaspernowak
Can’t promise it 100%, but likely sometime in August or September.

It’s quite a big refactor, and we want to do it properly. I’ve planned around 2–3 days to review, adjust, and test it thoroughly.

But if that’s too long for you, feel free to create a fork and merge it there in the meantime.

@kaspernowak
Copy link
Contributor Author

@StanBarrows Thank you! Hopefully we won't need this before you have time to look at it, but otherwise we will run this from a fork.

Do you mean this is a big refactor due to that apps you support currently use the current invoice approach? I feel like this PR alone adds more additional features than it affects existing functionality, and therefore I also feel like this is a much smaller refactor than the OAuth2 PR, but I might be wrong.

@StanBarrows
Copy link
Contributor

StanBarrows commented Jul 21, 2025 •
edited
Loading

@kaspernowak

As far as I know, your PR was built as an addition so that we can support both methods. I’d first like to review the current Bexio API documentation myself, since we developed this approach some time ago, and then decide whether to keep both or drop the existing implementation. It would also make sense to check if any other updates are needed for other objects, as there are still open PRs that involve further API changes. I'm just not updated about any changes to the Bexio API the last couple of years.

After that, Rhys will likely review your entire PR and process it and then update the documentation accordingly.

All in all, I need to set aside time to properly look into this — and after that, it’s up to Rhys. With a major go-live coming up in early August, even finding a few hours a day is currently not feasible.

P.S. The OAuth integration — even with your PR as a reference — still took about two full working days to reach its current state. So the current PR is maybe not more complex in a technical way, but it involves more research and coordination with other people, which makes it feel more complex to me. And yeah, then I’ll also need to update all the projects where I’ve implemented the current state, to avoid technical debt. And since this isn’t covered by any customer budget, I’ll have to fit it into time slots where I have some capacity.

@kaspernowak
Copy link
Contributor Author

@StanBarrows I completely understand, thank you for the explanation.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@RhysLees RhysLees Awaiting requested review from RhysLees

At least 1 approving review is required to merge this pull request.

Assignees

@RhysLees RhysLees

Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Feature Request | Invoice Endpoints
3 participants
@kaspernowak @StanBarrows @RhysLees